home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 October: Mac OS SDK / Dev.CD Oct 97 SDK1.toast / Development Kits (Disc 1) / Interfaces&Libraries / Universal / Interfaces / PInterfaces / Translation.p < prev    next >
Encoding:
Text File  |  1997-08-12  |  12.0 KB  |  311 lines  |  [TEXT/MPS ]
  1. {
  2.      File:        Translation.p
  3.  
  4.      Contains:    Translation Manager (Macintosh Easy Open) Interfaces.
  5.  
  6.      Version:    Technology:    Macintosh Easy Open 1.1
  7.                  Release:    Universal Interfaces 3.0.1
  8.  
  9.      Copyright:    © 1991-1997 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        Please include the the file and version information (from above) with
  12.                  the problem description.  Developers belonging to one of the Apple
  13.                  developer programs can submit bug reports to:
  14.  
  15.                      devsupport@apple.com
  16.  
  17. }
  18. {$IFC UNDEFINED UsingIncludes}
  19. {$SETC UsingIncludes := 0}
  20. {$ENDC}
  21.  
  22. {$IFC NOT UsingIncludes}
  23.  UNIT Translation;
  24.  INTERFACE
  25. {$ENDC}
  26.  
  27. {$IFC UNDEFINED __TRANSLATION__}
  28. {$SETC __TRANSLATION__ := 1}
  29.  
  30. {$I+}
  31. {$SETC TranslationIncludes := UsingIncludes}
  32. {$SETC UsingIncludes := 1}
  33.  
  34. {$IFC UNDEFINED __TYPES__}
  35. {$I Types.p}
  36. {$ENDC}
  37. {$IFC UNDEFINED __FILES__}
  38. {$I Files.p}
  39. {$ENDC}
  40. {$IFC UNDEFINED __COMPONENTS__}
  41. {$I Components.p}
  42. {$ENDC}
  43. {$IFC UNDEFINED __TRANSLATIONEXTENSIONS__}
  44. {$I TranslationExtensions.p}
  45. {$ENDC}
  46.  
  47.  
  48. {$PUSH}
  49. {$ALIGN MAC68K}
  50. {$LibExport+}
  51.  
  52. {  enumerated types on how a document can be opened }
  53.  
  54. TYPE
  55.     DocOpenMethod                        = INTEGER;
  56.  
  57. CONST
  58.     domCannot                    = 0;
  59.     domNative                    = 1;
  60.     domTranslateFirst            = 2;
  61.     domWildcard                    = 3;
  62.  
  63. {  0L terminated array of OSTypes, or FileTypes }
  64.  
  65. TYPE
  66.     TypesBlock                            = ARRAY [0..63] OF OSType;
  67.     TypesBlockPtr                        = ^OSType;
  68. {  Progress dialog resource ID }
  69.  
  70. CONST
  71.     kTranslationScrapProgressDialogID = -16555;
  72.  
  73. {  block of data that describes how to translate }
  74.  
  75. TYPE
  76.     FileTranslationSpecPtr = ^FileTranslationSpec;
  77.     FileTranslationSpec = RECORD
  78.         componentSignature:        OSType;
  79.         translationSystemInfo:    Ptr;
  80.         src:                    FileTypeSpec;
  81.         dst:                    FileTypeSpec;
  82.     END;
  83.  
  84.     FileTranslationSpecArrayPtr            = ^FileTranslationSpec;
  85. {****************************************************************************************
  86. * 
  87. *   GetFileTypesThatAppCanNativelyOpen
  88. * 
  89. *  This routine returns a list of all FileTypes that an application can open by itself
  90. * 
  91. *  Enter:    appVRefNumHint        volume where application resides (can be wrong, and if is, will be used as a starting point)
  92. *             appSignature        signature (creator) of application
  93. *             nativeTypes            pointer to a buffer to be filled with up to 64 FileTypes
  94. * 
  95. *  Exit:    nativeTypes            zero terminated array of FileTypes that can be opened by app
  96. }
  97. FUNCTION GetFileTypesThatAppCanNativelyOpen(appVRefNumHint: INTEGER; appSignature: OSType; VAR nativeTypes: FileType): OSErr;
  98.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  99.     INLINE $701C, $ABFC;
  100.     {$ENDC}
  101. {****************************************************************************************
  102. * 
  103. *  ExtendFileTypeList
  104. * 
  105. *  This routine makes a new list of file types that can be translated into a type in the given list
  106. *  Used by StandardFile
  107. * 
  108. *  Enter:    originalTypeList        pointer to list of file types that can be opened
  109. *             numberOriginalTypes        number of file types in orgTypeList
  110. *              extendedTypeList        pointer to a buffer to be filled with file types
  111. *             numberExtendedTypes        max number of file types that can be put in extendedTypeList
  112. * 
  113. *  Exit:    extendedTypeList        buffer filled in with file types that can be translated
  114. *             numberExtendedTypes        number of file types put in extendedTypeList
  115. }
  116. FUNCTION ExtendFileTypeList({CONST}VAR originalTypeList: FileType; numberOriginalTypes: INTEGER; VAR extendedTypeList: FileType; VAR numberExtendedTypes: INTEGER): OSErr;
  117.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  118.     INLINE $7009, $ABFC;
  119.     {$ENDC}
  120.  
  121. {****************************************************************************************
  122. * 
  123. * 
  124. *  This routine checks if a file can be opened by a particular application.
  125. *  If so, it returns if it needs to be translated first, and if so then how.
  126. *  The FileTypes that the app can open are specified by nativelyOpenableTypes,
  127. *  or if it is NULL, GetFileTypesThatAppCanNativelyOpen is called.
  128. * 
  129. *  Enter:    targetDocument        document to check if it can be opened
  130. *             appVRefNumHint        vRefNum of application to open doc ( can be wrong, and if is, will be used as a starting point)
  131. *             appSignature        signature (creator) of application to open doc
  132. *             nativeTypes            zero terminated list of FileTypes app can open natively, or NULL to use default list
  133. *             onlyNative            whether to consider if document can be translated before opening
  134. *             howToOpen            pointer to buffer in which to put how the document can be opened
  135. *             howToTranslate        pointer to buffer in which to put a FileTranslationSpec record
  136. * 
  137. *  Exit:    howToOpen            whether file needs to be translated to be read
  138. *             howToTranslate        if file can be translated, buffer filled in with how to translate
  139. *             returns                noErr, noPrefAppErr
  140. }
  141. FUNCTION CanDocBeOpened({CONST}VAR targetDocument: FSSpec; appVRefNumHint: INTEGER; appSignature: OSType; {CONST}VAR nativeTypes: FileType; onlyNative: BOOLEAN; VAR howToOpen: DocOpenMethod; VAR howToTranslate: FileTranslationSpec): OSErr;
  142.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  143.     INLINE $701E, $ABFC;
  144.     {$ENDC}
  145.  
  146. {****************************************************************************************
  147. * 
  148. *  GetFileTranslationPaths
  149. * 
  150. *  This routine returns a list of all ways a translation can occure to or from a FileType.
  151. *  The app is checked to exist.  The hint for each app is the VRefNum and DTRefNum
  152. * 
  153. *  Enter:    srcDoc            source file or NULL for all matches
  154. *             dstDoc            destination FileType or NULL for all matches
  155. *             maxResultCount
  156. *             resultBuffer
  157. *  Exit:    number of paths
  158. }
  159. FUNCTION GetFileTranslationPaths(VAR srcDocument: FSSpec; dstDocType: FileType; maxResultCount: INTEGER; resultBuffer: FileTranslationSpecArrayPtr): INTEGER;
  160.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  161.     INLINE $7038, $ABFC;
  162.     {$ENDC}
  163. {****************************************************************************************
  164. * 
  165. *  GetPathFromTranslationDialog
  166. * 
  167. *  This routine, with a given document, application, and a passed typelist will display the
  168. *  Macintosh Easy Open translation dialog allowing the user to make a choice.  The choice
  169. *  made will be written as a preference (so the next call to CanDocBeOpened() will work).
  170. *  The routine returns the translation path information.
  171. * 
  172. *  Enter:    theDocument            FSSpec to document to open
  173. *             theApplication        FSSpec to application to open document
  174. *             typeList            Nil terminated list of FileType's (e.g. SFTypeList-like) of types
  175. *                                 you would like the documented translated to.  Order most perferred
  176. *                                 to least.
  177. * 
  178. *  Exit:    howToOpen            Translation method needed to open document
  179. *             howToTranslate        Translation specification
  180. *             returns                Any errors that might occur.
  181. }
  182. FUNCTION GetPathFromTranslationDialog({CONST}VAR theDocument: FSSpec; {CONST}VAR theApplication: FSSpec; typeList: TypesBlockPtr; VAR howToOpen: DocOpenMethod; VAR howToTranslate: FileTranslationSpec): OSErr;
  183.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  184.     INLINE $7037, $ABFC;
  185.     {$ENDC}
  186.  
  187. {****************************************************************************************
  188. * 
  189. *   TranslateFile
  190. * 
  191. *  This routine reads a file of one format and writes it to another file in another format. 
  192. *  The information on how to translated is generated by the routine CanDocBeOpened.
  193. *  TranslateFile calls through to the TranslateFile Extension's DoTranslateFile routine.  
  194. *  The destination file must not exist.  It is created by this routine.  
  195. * 
  196. *  Enter:    sourceDocument            input file to translate
  197. *             destinationDocument        output file of translation
  198. *             howToTranslate            pointer to info on how to translate
  199. *  Exit:    returns                    noErr, badTranslationSpecErr 
  200. }
  201. FUNCTION TranslateFile({CONST}VAR sourceDocument: FSSpec; {CONST}VAR destinationDocument: FSSpec; {CONST}VAR howToTranslate: FileTranslationSpec): OSErr;
  202.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  203.     INLINE $700C, $ABFC;
  204.     {$ENDC}
  205. {****************************************************************************************
  206. * 
  207. *   GetDocumentKindString
  208. * 
  209. *  This routine returns the string the Finder should show for the "kind" of a document
  210. *  in the GetInfo window and in the kind column of a list view.  
  211. * 
  212. *  Enter:    docVRefNum        The volume containing the document
  213. *             docType            The catInfo.fdType of the document
  214. *             docCreator        The catInfo.fdCreator of the document
  215. *             kindString        pointer to where to return the string
  216. * 
  217. *  Exit:    kindString        pascal string.  Ex: "\pSurfCalc spreadsheet"
  218. *             returns            noErr, or afpItemNoFound if kind could not be determined
  219. }
  220. FUNCTION GetDocumentKindString(docVRefNum: INTEGER; docType: OSType; docCreator: OSType; VAR kindString: Str63): OSErr;
  221.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  222.     INLINE $7016, $ABFC;
  223.     {$ENDC}
  224. {****************************************************************************************
  225. * 
  226. *  GetTranslationExtensionName
  227. * 
  228. *  This routine returns the translation system name from a specified TranslationSpec
  229. * 
  230. *  Enter:    translationMethod    The translation path to get the translation name from
  231. * 
  232. *  Exit:    extensionName        The name of the translation system
  233. *             returns                Any errors that might occur
  234. }
  235. FUNCTION GetTranslationExtensionName({CONST}VAR translationMethod: FileTranslationSpec; VAR extensionName: Str31): OSErr;
  236.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  237.     INLINE $7036, $ABFC;
  238.     {$ENDC}
  239.  
  240. {****************************************************************************************
  241. * 
  242. *  GetScrapDataProcPtr
  243. * 
  244. *  This is a prototype for the function you must supply to TranslateScrap. It is called to 
  245. *  get the data to be translated.  The first call TranslateScrap will make to this is to
  246. *  ask for the 'fmts' data.  That is a special.   You should resize and fill in the handle
  247. *  with a list all the formats that you have available to be translated, and the length of each.
  248. *  (See I.M. VI 4-23 for details of 'fmts').  It will then be called again asking for one of  
  249. *  the formats that 'fmts' list said was available.
  250. * 
  251. *  Enter:    requestedFormat            Format of data that TranslateScrap needs.
  252. *             dataH                    Handle in which to put the requested data
  253. *             srcDataGetterRefCon        Extra parameter for you passed to TranslateScrap
  254. *             
  255. *  Exit:    dataH                    Handle is resized and filled with data in requested format
  256. }
  257.  
  258. TYPE
  259.     GetScrapDataProcPtr = ProcPtr;  { FUNCTION GetScrapData(requestedFormat: ScrapType; dataH: Handle; srcDataGetterRefCon: UNIV Ptr): OSErr; }
  260.  
  261.     GetScrapDataUPP = UniversalProcPtr;
  262.  
  263. CONST
  264.     uppGetScrapDataProcInfo = $00000FE0;
  265.  
  266. FUNCTION NewGetScrapDataProc(userRoutine: GetScrapDataProcPtr): GetScrapDataUPP;
  267.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  268.     INLINE $2E9F;
  269.     {$ENDC}
  270.  
  271. FUNCTION CallGetScrapDataProc(requestedFormat: ScrapType; dataH: Handle; srcDataGetterRefCon: UNIV Ptr; userRoutine: GetScrapDataUPP): OSErr;
  272.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  273.     INLINE $205F, $4E90;
  274.     {$ENDC}
  275.  
  276. TYPE
  277.     GetScrapData                        = GetScrapDataUPP;
  278. {****************************************************************************************
  279. * 
  280. *  TranslateScrap
  281. * 
  282. *  This routine resizes the destination handle and fills it with data of the requested format.
  283. *  The data is generated by translated one or more source formats of data supplied by
  284. *  the procedure srcDataGetter.  
  285. *  This routine is automatically called by GetScrap and ReadEdition.  You only need to call
  286. *  this if you need to translated scrap style data, but are not using the ScrapMgr or EditionMgr.
  287. * 
  288. *  Enter:    sourceDataGetter            Pointer to routine that can get src data
  289. *             sourceDataGetterRefCon        Extra parameter for dataGetter
  290. *             destinationFormat            Format of data desired
  291. *             destinationData                Handle in which to store translated data
  292. *             
  293. *  Exit:    dstData                        Handle is resized and filled with data in requested format
  294. }
  295. FUNCTION TranslateScrap(sourceDataGetter: GetScrapData; sourceDataGetterRefCon: UNIV Ptr; destinationFormat: ScrapType; destinationData: Handle; progressDialogID: INTEGER): OSErr;
  296.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  297.     INLINE $700E, $ABFC;
  298.     {$ENDC}
  299.  
  300.  
  301. {$ALIGN RESET}
  302. {$POP}
  303.  
  304. {$SETC UsingIncludes := TranslationIncludes}
  305.  
  306. {$ENDC} {__TRANSLATION__}
  307.  
  308. {$IFC NOT UsingIncludes}
  309.  END.
  310. {$ENDC}
  311.